Inside Macintosh: Programming With the Text Encoding Conversion Manager /

Chapter 4 - Unicode Converter Reference / Application-Defined Function

/

MyUnicodeToTextFallbackProc

Converts a Unicode text element for which there is no destination encoding equivalent in the appropriate mapping table to the fallback character sequence defined by your fallback handler, and returns the converted character sequence to the Unicode Converter.

pascal OSStatus MyUnicodeToTextFallbackProc(
      UniChar *iSrcUniStr, 
      ByteCount iSrcUniStrLen, 
      ByteCount *oSrcConvLen,
      TextPtr *oDestStr,
      ByteCount iDestStrLen,
      ByteCount *oDestConvLen,
      LogicalAddress *iInfoPtr
      ConstUnicodeMappingPtr iUnicodeMappingPtr);

iSrcUniStr

A pointer to a single UTF-16 character to be mapped by the fallback handler.

iSrcUniStrLen

The length in bytes of the UTF-16 character indicated by the iSrcUniStr parameter. Usually this is 2 bytes, but it could be 4 bytes for a non-BMP character.

oSrcConvLen

A pointer to a value of type ByteCount. On output, the length in bytes of the portion of the Unicode character that was actually processed by your fallback handler. Your fallback handler returns this value. It should set this to 0 if none of the text was handled, or 2 or 4 if the Unicode character was handled. This value is initialized to 0 before the fallback handler is called.

oDestStr

A pointer to the output buffer where your handler should place any converted text.

iDestStrLen

The maximum size in bytes of the buffer provided by the oDestStr parameter.

oDestConvLen

A pointer to a value of type ByteCount. On output, the length in bytes of the fallback character sequence generated by your fallback handler. Your handler should return this length. It is initialized to 0 (zero) before the fallback handler is called.

iInfoPtr

A pointer to a block of memory allocated by your application, which can be used by your fallback handler in any way that you like. This is the same pointer passed as the last parameter of SetFallbackUnicodeToText or SetFallbackUnicodeToTextRun. How you use the data passed to you in this memory block is particular to your handler. This is similar in use to a reference constant (refcon).

iUnicodeMappingPtr

A constant pointer to a structure of type UnicodeMapping (page 118). This structure identifies a Unicode encoding specification and a particular base encoding specification.

function result

A result code. See "Text Encoding Conversion Manager Result Codes" (page 42) in the chapter "Basic Text Types Reference."

DISCUSSION

The Unicode Converter calls your fallback handler when it cannot convert a text string using the mapping table specified by the Unicode converter object passed to either ConvertFromUnicodeToText or ConvertFromUnicodeToPString. The control flags you set for the controlFlags parameter of the function SetFallbackUnicodeToText (page 172) or the SetFallbackUnicodeToTextRun (page 175) stipulate which fallback handler the Unicode Converter should call and which one to try first if both can be used.

When the Unicode Converter calls your handler, it passes to it the Unicode character to be converted and its length, a buffer for the converted string you return and the buffer length, and a pointer to a block of memory containing the data your application supplied to be passed on to your fallback handler. For a description of the function prototype your handler should adhere to, see UnicodeToTextFallbackProcPtr (page 122).

After you convert the Unicode text segment to fallback characters, you return the fallback character sequence of the converted text in the buffer provided to you and the length in bytes of this fallback character sequence. You also return the length in bytes of the portion of the source Unicode text element that your handler actually processed.

You provide a fallback-handler function for use with the function CreateUnicodeToTextInfoByEncoding (page 136), ConvertFromUnicodeToPString (page 165), ConvertFromUnicodeToTextRun (page 150), or ConvertFromUnicodeToScriptCodeRun (page 155). You associate an application-defined fallback handler with a particular Unicode converter object you intend to pass to the conversion function when you call it.

Your handler should return noErr if it can handle the fallback, or kTECUnmappableElementErr if it cannot. It can return other errors for exceptional conditions, such as when the output buffer is too small. If your handler returns kTECUnmappableElementErr, then oSrcConvLen and oDestConvLen are ignored because either the default handler will be called or the default fallback sequence will be used.

Text converted from UTF-8 will already have been converted to UTF-16 before the fallback handler is called to process it. Your fallback handler should do all of its processing on text encoded in UTF-16.

Your application-defined fallback handler should not move memory or call any toolbox function that would move memory. If it needs memory, the memory should be allocated before the call to SetFallbackUnicodeToText or SetFallbackUnicodeToTextRun, and a memory reference should be passed either directly as iInfoPtr or in the data referenced by iInfoPtr.

To associate a fallback-handler function with a Unicode converter object you use the SetFallbackUnicodeToText (page 172) and SetFallbackUnicodeToTextRun (page 175) functions. For these functions, you must pass a universal procedure pointer (UniversalProcPtr). This is derived from a pointer to your function by using the predefined macro NewUnicodeToTextFallbackProc.

For versions of the Unicode Converter prior to 1.2, the fallback handler may receive a multiple character text element, so the source string length value could be greater than 2 and the fallback handler may set srcConvLen to a value greater than 2. In versions earlier than 1.2.1, the srcConvLen and destConvLen variables are not initialized to 0; both values are ignored unless the fallback handler returns noErr.

For a complete description of how to use universal procedure pointers, refer to Inside Macintosh: PowerPC System Software.